<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>File::Random - Perl module for random selecting of a file - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of File-Random - MetaCPAN" href="https://metacpan.org/dist/File-Random/releases.rss" />
        <link rel="canonical" href="./File::Random.html" />
        <meta name="description" content="Perl module for random selecting of a file" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/File::Random" />
<meta name="twitter:title"       content="File::Random" />
<meta name="twitter:description" content="Perl module for random selecting of a file" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./File::Random.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of File-Random was released.">
      <span class="relatize">10 Apr 2021 05:42:27 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/File-Random">File-Random</a>
  </li>
  <li>
    Module version: 0.21
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/File-Random/source/Random.pm">Source</a>
    (<a href="https://metacpan.org/dist/File-Random/source/Random.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/File-Random/source">Browse</a>
    (<a href="https://metacpan.org/dist/File-Random/source?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/File-Random/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/File-Random/contribute">How to Contribute</a>
    </li>
    <li>
        <a rel="noopener nofollow" data-keyboard-shortcut="g r" href="https://github.com/hanfried/File-Random">Repository</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=File-Random">Issues</a>
      (0)
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=File-Random+0.21" title="Matrix">Testers</a>
        <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/F/File-Random.html?oncpan=1&amp;distmat=1&amp;version=0.21&amp;grade=2" style="color: #090">139</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/F/File-Random.html?oncpan=1&amp;distmat=1&amp;version=0.21&amp;grade=3" style="color: #900">0</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/F/File-Random.html?oncpan=1&amp;distmat=1&amp;version=0.21&amp;grade=4">0</a>)</span>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/BIGJ/File-Random-0.21">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on File-Random who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 1
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/File-Random-0.21/index.html">94.15% Coverage </a>
    </li>
    <li>
      License: perl_5
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/File-Random/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/B/BI/BIGJ/File-Random-0.21.tar.gz">
      Download (<span itemprop="fileSize">13.67KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FBIGJ%2FFile-Random-0.21%2FRandom.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/File-Random/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/File-Random/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:File-Random">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="File-Random">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/Random.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="BIGJ/File-Random-0.21"
>0.21
  (BIGJ on 2021-04-10)</option>
<option
  
  value="BIGJ/File-Random-0.20"
>0.20
  (BIGJ on 2021-04-06)</option>
<option
  
  value="BIGJ/File-Random-0.19"
>0.19
  (BIGJ on 2020-05-05)</option>
<option
  
  value="BIGJ/File-Random-0.18"
>0.18
  (BIGJ on 2017-10-22)</option>
<option
  
  value="BIGJ/File-Random-0.17"
>0.17
  (BIGJ on 2002-08-20)</option>
<option
  
  value="BIGJ/File-Random-0.16"
>0.16
  (BIGJ on 2002-08-19)</option>
<option
  
  value="BIGJ/File-Random-0.15"
>0.15
  (BIGJ on 2002-08-16)</option>
<option
  
  value="BIGJ/File-Random-0.13"
>0.13
  (BIGJ on 2002-07-16)</option>
<option
  
  value="BIGJ/File-Random-0.12"
>0.12
  (BIGJ on 2002-07-03)</option>
<option
  
  value="BIGJ/File-Random-0.11"
>0.11
  (BIGJ on 2002-06-27)</option>
<option
  
  value="BIGJ/File-Random-0.10"
>0.10
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.09"
>0.09
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.08"
>0.08
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.07"
>0.07
  (BIGJ on 2002-06-25)</option>
<option
  
  value="BIGJ/File-Random-0.06"
>0.06
  (BIGJ on 2002-06-25)</option>
<option
  
  value="BIGJ/File-Random-0.05"
>0.05
  (BIGJ on 2002-06-20)</option>
<option
  
  value="BIGJ/File-Random-0.04"
>0.04
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.03"
>0.03
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.02"
>0.02
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.01"
>0.01
  (BIGJ on 2002-06-18)</option>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/BIGJ/File-Random-0.21/diff/' + encodeURIComponent(this.value) + '/Random.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="BIGJ/File-Random-0.21"
>0.21
  (BIGJ on 2021-04-10)</option>
<option
  
  value="BIGJ/File-Random-0.20"
>0.20
  (BIGJ on 2021-04-06)</option>
<option
  
  value="BIGJ/File-Random-0.19"
>0.19
  (BIGJ on 2020-05-05)</option>
<option
  
  value="BIGJ/File-Random-0.18"
>0.18
  (BIGJ on 2017-10-22)</option>
<option
  
  value="BIGJ/File-Random-0.17"
>0.17
  (BIGJ on 2002-08-20)</option>
<option
  
  value="BIGJ/File-Random-0.16"
>0.16
  (BIGJ on 2002-08-19)</option>
<option
  
  value="BIGJ/File-Random-0.15"
>0.15
  (BIGJ on 2002-08-16)</option>
<option
  
  value="BIGJ/File-Random-0.13"
>0.13
  (BIGJ on 2002-07-16)</option>
<option
  
  value="BIGJ/File-Random-0.12"
>0.12
  (BIGJ on 2002-07-03)</option>
<option
  
  value="BIGJ/File-Random-0.11"
>0.11
  (BIGJ on 2002-06-27)</option>
<option
  
  value="BIGJ/File-Random-0.10"
>0.10
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.09"
>0.09
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.08"
>0.08
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.07"
>0.07
  (BIGJ on 2002-06-25)</option>
<option
  
  value="BIGJ/File-Random-0.06"
>0.06
  (BIGJ on 2002-06-25)</option>
<option
  
  value="BIGJ/File-Random-0.05"
>0.05
  (BIGJ on 2002-06-20)</option>
<option
  
  value="BIGJ/File-Random-0.04"
>0.04
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.03"
>0.03
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.02"
>0.02
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.01"
>0.01
  (BIGJ on 2002-06-18)</option>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><a href="https://metacpan.org/pod/File::Temp" title="File::Temp" class="ellipsis">File::Temp</a></li>
  <li><a href="https://metacpan.org/pod/Set::Scalar" title="Set::Scalar" class="ellipsis">Set::Scalar</a></li>
  <li><a href="./Test::Class.html" title="Test::Class" class="ellipsis">Test::Class</a></li>
  <li><a href="./Test::Exception.html" title="Test::Exception" class="ellipsis">Test::Exception</a></li>
  <li><a href="https://metacpan.org/pod/Test::ManyParams" title="Test::ManyParams" class="ellipsis">Test::ManyParams</a></li>
  <li><a href="https://metacpan.org/pod/Test::More" title="Test::More" class="ellipsis">Test::More</a></li>
  <li><a href="https://metacpan.org/pod/Test::Warn" title="Test::Warn" class="ellipsis">Test::Warn</a></li>
  <li><a href="https://metacpan.org/pod/Want" title="Want" class="ellipsis">Want</a></li>
  <li><i class="ttip" title="dynamic_config enabled">and possibly others</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/File::Random/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=File%3A%3ARandom">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=File-Random">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/BIGJ/File-Random-0.21/view/Random.pm">This version</a>
    </li>
    <li>
      <a href="./File::Random.html">Latest version</a>
    </li>
    <li>
    </li>
    <li>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/BIGJ" class="author-name">Janek Schleicher</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/Random.pm&#39;" class="">
<option
  selected
  value="BIGJ/File-Random-0.21"
>0.21
  (BIGJ on 2021-04-10)</option>
<option
  
  value="BIGJ/File-Random-0.20"
>0.20
  (BIGJ on 2021-04-06)</option>
<option
  
  value="BIGJ/File-Random-0.19"
>0.19
  (BIGJ on 2020-05-05)</option>
<option
  
  value="BIGJ/File-Random-0.18"
>0.18
  (BIGJ on 2017-10-22)</option>
<option
  
  value="BIGJ/File-Random-0.17"
>0.17
  (BIGJ on 2002-08-20)</option>
<option
  
  value="BIGJ/File-Random-0.16"
>0.16
  (BIGJ on 2002-08-19)</option>
<option
  
  value="BIGJ/File-Random-0.15"
>0.15
  (BIGJ on 2002-08-16)</option>
<option
  
  value="BIGJ/File-Random-0.13"
>0.13
  (BIGJ on 2002-07-16)</option>
<option
  
  value="BIGJ/File-Random-0.12"
>0.12
  (BIGJ on 2002-07-03)</option>
<option
  
  value="BIGJ/File-Random-0.11"
>0.11
  (BIGJ on 2002-06-27)</option>
<option
  
  value="BIGJ/File-Random-0.10"
>0.10
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.09"
>0.09
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.08"
>0.08
  (BIGJ on 2002-06-26)</option>
<option
  
  value="BIGJ/File-Random-0.07"
>0.07
  (BIGJ on 2002-06-25)</option>
<option
  
  value="BIGJ/File-Random-0.06"
>0.06
  (BIGJ on 2002-06-25)</option>
<option
  
  value="BIGJ/File-Random-0.05"
>0.05
  (BIGJ on 2002-06-20)</option>
<option
  
  value="BIGJ/File-Random-0.04"
>0.04
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.03"
>0.03
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.02"
>0.02
  (BIGJ on 2002-06-19)</option>
<option
  
  value="BIGJ/File-Random-0.01"
>0.01
  (BIGJ on 2002-06-18)</option>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/File-Random">File-Random-0.21</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage zero &#10;
          No dependents
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="5"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="10"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="File-Random-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="File-Random-0.21">
    <input type="hidden" name="author" value="BIGJ">
    <input type="hidden" name="distribution" value="File-Random">
    <button type="submit" class="favorite"><span></span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./File::Random.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite">
<span></span> ++</a>
</div>
   / <span>File::Random</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./File::Random.html#NAME">NAME</a></li>
  <li><a href="./File::Random.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./File::Random.html#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="./File::Random.html#FUNCTION">FUNCTION</a>
    <ul>
      <li><a href="./File::Random.html#random_file">random_file</a></li>
      <li><a href="./File::Random.html#FUNCTION-content_of_random_file-(or-corf)">FUNCTION content_of_random_file (or corf)</a></li>
      <li><a href="./File::Random.html#FUNCTION-random_line($filename-%5B,-$nr_of_lines%5D)">FUNCTION random_line($filename [, $nr_of_lines])</a></li>
      <li><a href="./File::Random.html#EXPORT">EXPORT</a></li>
    </ul>
  </li>
  <li><a href="./File::Random.html#DEPENDENCIES">DEPENDENCIES</a></li>
  <li><a href="./File::Random.html#TODO">TODO</a></li>
  <li><a href="./File::Random.html#BUGS">BUGS</a></li>
  <li><a href="./File::Random.html#COPYRIGHT">COPYRIGHT</a></li>
  <li><a href="./File::Random.html#AUTHOR">AUTHOR</a></li>
  <li><a href="./File::Random.html#SEE-ALSO">SEE ALSO</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p>File::Random - Perl module for random selecting of a file</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code>  use File::Random qw/:all/;
 
  my $fname  = random_file();

  my $fname2 = random_file(-dir =&gt; $dir);
  
  my $random_gif = random_file(
    -dir       =&gt; $dir,
    -check     =&gt; qr/\.gif$/,
        -recursive =&gt; 1,
    -follow =&gt; 1
  );
                                                           
  my $no_exe     = random_file(
    -dir   =&gt; $dir,
    -check =&gt; sub {! -x}
  );
                                                           
  my @jokes_of_the_day = content_of_random_file(-dir =&gt; &#39;/usr/lib/jokes&#39;);
  my $joke_of_the_day  = content_of_random_file(-dir =&gt; &#39;/usr/lib/jokes&#39;);
  # or the shorter
  my $joke = corf(-dir =&gt; &#39;/usr/lib/jokes&#39;);
  
  my $word_of_the_day = random_line(&#39;/usr/share/dict/words&#39;);
  my @three_words     = random_line(&#39;/usr/share/dict/words&#39;,3);
  # or
  my ($title,$speech,$conclusion) = random_line(&#39;/usr/share/dict/words&#39;);</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>This module simplifies the routine job of selecting a random file. (As you can find at CGI scripts).</p>

<p>It&#39;s done, because it&#39;s boring (and errorprone), always to write something like</p>

<pre><code>  my @files = (&lt;*.*&gt;);
  my $randf = $files[rand @files];
  </code></pre>

<p>or</p>

<pre><code>  opendir DIR, &quot; ... &quot; or die &quot; ... &quot;;
  my @files = grep {-f ...} (readdir DIR);
  closedir DIR;
  my $randf = $files[rand @files];
 </code></pre>

<p>It also becomes very boring and very dangerous to write randomly selection for subdirectory searching with special check-routines.</p>

<p>The simple standard job of selecting a random line from a file is implemented, too.</p>

<h1 id="FUNCTION">FUNCTION</h1>

<h2 id="random_file">random_file</h2>

<p>Returns a randomly selected file(name) from the specified directory If the directory is empty, undef is returned. There are 3 options:</p>

<pre><code>  my $file = random_file(
     -dir         =&gt; $dir, 
         -check       =&gt; qr/.../, # or sub { .... }
         -recursive   =&gt; 1        # or 0
  );
  </code></pre>

<p>Let&#39;s have a look to the options:</p>

<dl>

<dt id="-dir-(-d-or-directory)"><a id="dir---d-or-directory"></a>-dir (-d or -directory)</dt>
<dd>

<p>Specifies the directory where file has to come from.</p>

<p>If no <code>-dir</code> option is specified, a random file from the current directory will be used. That means &#39;.&#39; is the default for the <code>-dir</code> option.</p>

</dd>
<dt id="-check-(-c)"><a id="check---c"></a>-check (-c)</dt>
<dd>

<p>With the <code>-check</code> option you can either define a regex every filename has to follow, or a sub routine which gets the filename as argument. The filename passed as argument includes the relative path (relative to the <code>-dir</code> directory or the current directory). The argument is passed implicit as localized value of <code>$_</code> and it is also the first parameter on the argument array <code>$_[0]</code>.</p>

<p>Note, that <code>-check</code> doesn&#39;t accept anything else than a regexp or a subroutine. A string like &#39;/.../&#39; won&#39;t work.</p>

<p>The default is no checking (undef).</p>

</dd>
<dt id="-recursive-(-r-or-rec)"><a id="recursive---r-or-rec"></a>-recursive (-r or -rec)</dt>
<dd>

<p>Enables, that subdirectories are scanned for files, too. Every file, independent from its position in the file tree, has the same chance to be choosen. Now the relative path from the given subdirectory or the current directory of the randomly choosen file is included to the file name.</p>

<p>Every true value sets recursive behaviour on, every false value switches off. The default if false (undef).</p>

<p>Note, that I programmed the recursive routine very defendly (using <code>File::Find</code>). So switching -recursive on, slowers the program a bit :-) Please look to the <code>File::Find</code> module for any details and bugs related to recursive searching of files.</p>

</dd>
<dt id="-follow-(-f)"><a id="follow---f"></a>-follow (-f)</dt>
<dd>

<p>Follow symlinks when in recursive mode. See <code>File::Find</code> for details. Default is not to follow.</p>

</dd>
<dt id="unknown-options"><a id="unknown"></a>unknown options</dt>
<dd>

<p>Gives a warning. Unknown options are ignored. Note, that upper/lower case makes a difference.</p>

</dd>
</dl>

<h2 id="FUNCTION-content_of_random_file-(or-corf)"><a id="FUNCTION1"></a><a id="FUNCTION-content_of_random_file--or-corf"></a>FUNCTION content_of_random_file (or corf)</h2>

<p>Returns the content of a randomly selected random file. In list context it returns an array of the lines of the selected file, in scalar context it returns a multiline string with whole the file. The lines aren&#39;t chomped.</p>

<p>This function has the same parameters and a similar behaviour to the <code>random_file</code> method. Note, that <code>-check</code> option still gets passed the filename and not the file content.</p>

<p>Instead of the long <code>content_of_random_file</code>, you can also use the alias <code>corf</code> (but don&#39;t forget to say either <code>use File::Random qw/:all/</code> or <code>use File::Random qw/corf/</code>)</p>

<h2 id="FUNCTION-random_line($filename-[,-$nr_of_lines])"><a id="FUNCTION2"></a><a id="FUNCTION-random_line-filename----nr_of_lines"></a>FUNCTION random_line($filename [, $nr_of_lines])</h2>

<p>Returns one or <code>$nr_of_lines</code> random_lines from an (existing) file.</p>

<p>If the file is empty, undef is returned.</p>

<p>The algorithm used for returning one line is the one from the FAQ. See <code>perldoc -q &quot;random line&quot;</code> for details. For more than one line (<code>$nr_of_lines &gt; 1</code>), I use nearly the same algorithm. Especially the returned lines aren&#39;t a sample, as a line could be returned doubled.</p>

<p>The result of <code>random_line($filename, $nr)</code> should be quite similar to <code>map {random_line($filename)} (1 .. $nr)</code>, only the last way is not so efficient, as the file would be read <code>$nr</code> times instead of one times.</p>

<p>It also works on large files, as the algorithm only needs two lines of the file at the same time in memory.</p>

<p><code>$nr_of_lines</code> is an optional argument which is 1 at default. Calling <code>random_line</code> in scalar context with <code>$nr_of_lines</code> greater than 1, gives a warning, as it doesn&#39;t make a lot of sense. I also gives you a warning of <code>$nr_of_lines</code> is zero.</p>

<p>You also can write something like</p>

<pre><code>  my ($line1, $line2, $line3) = random_line($fname);
  </code></pre>

<p>and random_line will return a list of 3 randomly choosen lines. Allthough <code>File::Random</code> tries its best to find out how many lines you wanted, it&#39;s not an oracle, so</p>

<pre><code>  my @line = random_line($fname);
  </code></pre>

<p>will be interpreted as</p>

<pre><code>  my @line = random_line($fname,1);</code></pre>

<h2 id="EXPORT">EXPORT</h2>

<p>None by default.</p>

<p>You can export the function random_file with <code>use File::Random qw/random_file/;</code>, <code>use File::Random qw/content_of_random_file/</code> or with the more simple <code>use File::Random qw/:all/;</code>.</p>

<p>I didn&#39;t want to pollute namespaces as I could imagine, users write methods random_file to create a file with random content. If you think I&#39;m paranoid, please tell me, then I&#39;ll take it into the export.</p>

<h1 id="DEPENDENCIES">DEPENDENCIES</h1>

<p>This module requires these other modules and libraries:</p>

<pre><code>  Want
  </code></pre>

<p>For the tests are also needed many more modules:</p>

<pre><code>  Test::More
  Test::Exception
  Test::Class
  Set::Scalar
  File::Temp
  Test::Warn
  Test::ManyParams</code></pre>

<p>All these modules are needed only for the tests. You can work with the module even without them. These modules are only needed for my test routines, not by the File::Random itself. (However, it&#39;s a good idea most to install most of the modules anyway).</p>

<h1 id="TODO">TODO</h1>

<p>A <code>-firstline</code> or <code>-lines =</code> [1 .. 10]&gt; option for the <code>content_of_random_file</code> could be useful.</p>

<p>Also speed could be improved, as I tried to write the code very readable, but wasted sometimes a little bit speed.</p>

<p>Please feel free to suggest me anything what could be useful.</p>

<h1 id="BUGS">BUGS</h1>

<p>Well, because as this module handles some random data, it&#39;s a bit harder to test. So a test could be wrong, allthough everything is O.K.. To avoid it, I let many tests run, so that the chances for misproofing should be &lt; 0.0000000001% or so. Even it has the disadvantage that the tests need really long :-(</p>

<p>I&#39;m not definitly sure whether my test routines runs on OS, with path seperators different of &#39;/&#39;, like in Win with &#39;\\&#39;. Perhaps anybody can try it and tell me the result. [But remember Win* is definitly the greater bug.]</p>

<h1 id="COPYRIGHT">COPYRIGHT</h1>

<p>This Program is free software. You can change or redistribute it under the same condition as Perl itself.</p>

<p>Copyright (c) 2002, Janek Schleicher, &lt;bigj@kamelfreund.de&gt;</p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>Janek Schleicher, &lt;bigj@kamelfreund.de&gt;</p>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<p><a href="https://metacpan.org/pod/Tie::Pick">Tie::Pick</a> <a href="https://metacpan.org/pod/Data::Random">Data::Random</a> <a href="https://metacpan.org/pod/Algorithm::Numerical::Sample">Algorithm::Numerical::Sample</a></p></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install File::Random, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm File::Random</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install File::Random</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./File::Random.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
